/*
 * IAudioPlayer.java
 *
 * Created on 2007��3��19��, ����1:47
 *
 * To change this template, choose Tools | Template Manager
 * and open the template in the editor.
 */

package com.zxh.audio;

import javax.sound.sampled.*;
import java.io.File;
import java.io.InputStream;
import java.net.URL;

/**
 *
 * @author ��˶
 */
public interface IAudioPlayer 
{
    /**
     * Load audio to playback from a URL
     *
     * @param url The url of the audio data
     * @throws Exception
     */
    public void loadAudio(URL url) throws Exception;

    /**
     * Load audio to playback from a File
     *
     * @param file The file of the audio data
     * @throws Exception
     */
    public void loadAudio(File file) throws Exception;

    /**
     * Load audio to playback from an InputStream
     *
     * @param inputStream The InputStream of the audio data
     * @throws Exception
     */
    public void loadAudio(InputStream inputStream) throws Exception;

    /**
     * begin playback of the audio
     */
    public void play();

    /**
     * Pause playback of the audio. Effectively stops playback without
     * resetting the playback position.
     *
     * @see #stop
     */
    public void pause();

    /**
     * Stops playback of the audio. Effectively stops playback and
     * resets the playback position to the beginning.
     *
     * @see #pause
     */
    public void stop();

    /**
     * Sets the gain amount to apply to the audio playback. Positive gain will raise the
     * amplitude and negative gain will lower it.
     *
     * @param dB the deci-Bell gain amount
     */
    public void setGain(float dB);

    /**
     * Sets the pan, or the stereo placement of the audio playback. -1 is all left channel,
     * 0 is center, and 1 is right
     *
     * @param pan the pan value. Between -1 and 1
     */
    public void setPan(float pan);

    /**
     * Clear the cached audip data
     */
    public void unloadAudio();

    /**
     * @return The playback Line's current playback position
     */
    public int getFramePosition();

    /**
     * @return The Line used for playback
     * @see Line
     */
    public Line getLine();

    /**
     *
     * @return The current format of the playback line
     * @see Line
     */
    public AudioFormat getCurrentFormat();

    /**
     * @return the AudioInputStream used to retrieve the audio data for playback
     */
    public AudioInputStream getAudioInputStream();
    
}
